Inside Macintosh: QuickTime Components
Movie controller components provide a number of functions that allow your application to control the display attributes of a movie controller. For example, you can detach the controller from its movie, so that the controller and movie can be managed as separate graphics entities. In addition, movie controller components provide a number of functions that allow you to work with a controller's boundary rectangles and regions. For a complete discussion of these rectangles and regions, see "Spatial Properties," which begins on Spatial Properties .
The MCSetControllerAttached function lets you control whether the movie controller is attached to its movie. The MCIsControllerAttached function allows you to determine if a controller is attached to its movie.
You can use the MCSetControllerPort and MCGetControllerPort functions to work a movie controller's graphics port.
The MCSetVisible and MCGetVisible functions enable you to control the visibility of the movie controller.
The MCSetControllerBoundsRect and MCGetControllerBoundsRect functions help you work with a movie controller's boundary rectangle. You can use the MCGetControllerBoundsRgn and MCGetControllerWindowRgn functions if the controller is not rectangular. You can position a controller and its movie separately by calling the MCPositionController function.
The MCPositionController function allows you to control the position of a movie and its controller on the computer display.
pascal ComponentResult MCPositionController (MovieController mc,
const Rect *movieRect,
const Rect *controllerRect,
long someFlags);
The MCSetControllerAttached function allows your application to control whether a movie controller is attached to its movie or detached from it. "About Movie Controller Components," which begins on About Movie Controller Components , discusses the differences between attached and detached movie controllers.
pascal ComponentResult MCSetControllerAttached
(MovieController mc,
Boolean attach);
Your application should not make any assumptions about the location of an attached movie controller with respect to its movie. The controller may be above, below, or surrounding the movie image.
If you need to know the location of the controller, you can use the MCGetControllerBoundsRect function, described on MCGetControllerBoundsRect , to obtain its boundary rectangle.
The MCIsControllerAttached function returns a value that indicates whether a movie controller is attached to its movie.
pascal ComponentResult MCIsControllerAttached
(MovieController mc);
The MCSetVisible function allows your application to control the visibility of a movie controller.
pascal ComponentResult MCSetVisible (MovieController mc,
Boolean visible);
Movie controller components support badges, which allow you to create a visual cue that helps the user distinguish between static images and images that represent movies. The movie controller component displays a badge in the movie image whenever the movie is visible but the control portion of the controller is not visible. To work with movie controller badges, you must use the mcActionSetUseBadge action, which is described in "Movie Controller Actions," .
By default, a new controller is hidden so that your application can freely set the display attributes before showing the controller to the user. You should note, however, that the MCNewAttachedController function (described on MCNewAttachedController ) automatically sets the movie controller to be visible. Your application must make the controller visible before the user can work with its associated movie.
The MCGetVisible function returns a value that indicates whether a movie controller is visible.
pascal ComponentResult MCGetVisible (MovieController mc);
The MCDrawBadge function allows you to display a controller's badge. This function places the badge in an appropriate location based on the location of the controller's movie.
pascal ComponentResult MCDrawBadge (MovieController mc,
RgnHandle movieRgn,
RgnHandle *badgeRgn);
The MCDrawBadge function can be useful in circumstances where you are using a movie controller component but do not want to incur the overhead of having the QuickTime movie in memory all the time. This function allows you to display the badge without having to display the movie. In addition, you can use the badge region to perform mouse-down event testing.
The MCSetControllerBoundsRect function lets you change the position and size of a movie controller. A controller's boundary rectangle encloses the control portion of the controller. In addition, in cases where the movie is attached to the controller, the boundary rectangle also encloses the movie. Note that changing the size of the boundary rectangle may result in the movie being resized as well, if the movie is attached to the controller.
pascal ComponentResult MCSetControllerBoundsRect
(MovieController mc,
const Rect *bounds);
Movie controller components can reject your request for a number of reasons. For example, some movie controller components may support only fixed-size controllers or controllers whose size is fixed in one dimension. Also, note that your application cannot change the location of an attached controller.
The movie controller component returns a value of controllerBoundsNotExact if the boundary rectangle has been changed but does not correspond to the rectangle you specified. In this case, the new boundary rectangle is always smaller than the requested rectangle.
The MCGetControllerBoundsRect function returns a movie controller's boundary rectangle. This rectangle reflects the size and location of the controller even if the controller is currently hidden. If the controller is detached from its movie, the rectangle encompasses only the controller, not the movie. If the controller is attached to its movie, the rectangle encompasses both the controller and the movie.
pascal ComponentResult MCGetControllerBoundsRect
(MovieController mc,
Rect *bounds);
The returned rectangle is the boundary rectangle for the region occupied by the controller and its movie (if the movie is attached to the controller), even if the controller is not rectangular.
Note that if the controller cannot obtain enough screen space, the movie controller component may return an empty rectangle.
You can use the MCGetControllerBoundsRgn function, described in the next section, to obtain the boundary region for a controller. You can use the MCGetWindowRgn function, described on MCGetWindowRgn , to determine the portion of the window that is currently in use by the controller.
Some movie controllers may not be rectangular in shape. The MCGetControllerBoundsRgn function returns the actual region occupied by the controller and its movie, if the movie is attached to the controller. If the movie is not attached to its controller, the boundary region encloses only the control portion of the controller. The rectangle returned by the MCGetControllerBoundsRect function (described in the previous section) bounds the region returned by MCGetControllerBoundsRgn .
pascal RgnHandle MCGetControllerBoundsRgn (MovieController mc);
As with the MCGetControllerBoundsRect function, the MCGetControllerBoundsRgn function returns a region that reflects the size, shape, and location of the controller, even if the controller is hidden. Your application must dispose of the returned region.
The MCGetControllerBoundsRgn function returns a handle to the boundary region. Your application must dispose of this region.
The MCGetWindowRgn function allows your application to determine the window region that is actually in use by a controller and its movie. The region returned by this function contains only the visible portions of the controller and its movie.
pascal RgnHandle MCGetWindowRgn (MovieController mc, WindowPtr w);
The returned region may consist of several discontiguous areas. For example, if a controller is detached from its movie, the window region may define separate areas for the movie and the controller. If you want to consider just the controller, you must subtract the movie from the returned region.
Your application must dispose of the returned region.
The MCGetWindowRgn function returns a handle to the window region. Your application must dispose of this region.
The MCSetClip function allows you to set a movie controller's clipping region. This clipping region is equivalent to the movie display clipping region supported by the Movie Toolbox.
pascal ComponentResult MCSetClip (MovieController mc,
RgnHandle theClip,
RgnHandle movieClip);
The MCGetClip function allows you to obtain information describing a movie controller's clipping regions.
pascal ComponentResult MCGetClip (MovieController mc,
RgnHandle *theClip,
RgnHandle *movieClip);
The MCSetControllerPort function allows your application to set the graphics port for a movie controller. You can use this function to place a movie and its associated movie controller in different graphics ports. If you are using an attached controller, both the controller and the movie's graphics ports are changed. If you are using a detached controller, this function changes only the graphics port of the control portion of the controller. You must use the Movie Toolbox's SetMovieGWorld function followed by the MCMovieChanged function to change other portions.
pascal ComponentResult MCSetControllerPort (MovieController mc,
CGrafPtr gp);
The movie controller component may use the foreground and background colors from the graphics port at the time the MCSetController function is called to colorize the movie controller.
Movie controller components use the MCSetControllerPort function each time you create a new movie controller. Hence, your component must be set to a valid port before creating a new movie controller.
The MCGetControllerPort function returns a movie controller's color graphics port.
pascal CGrafPtr MCGetControllerPort (MovieController mc);